Tools Overview

Tools give BindAI agents the ability to interact with application code and external systems. A tool is a callable capability that an agent can use when additional functionality is required. Tools can be used for:

Calling APIs
Querying databases
Searching documents
Performing calculations
Reading or writing application data
Executing business logic
Integrating with external services

Tools extend an agent beyond language generation by giving it access to deterministic operations and application capabilities.

What Is a Tool?

A BindAI tool represents an operation that an agent can execute. The underlying operation can be a normal Python function.

def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

A tool can then be attached to an agent:

agent.tool(get_weather)

Tools can also be registered during agent construction with the builder API.

Creating a Tool

BindAI provides a tool decorator for defining tools.

from bindai import tool


@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"The weather in {city} is sunny."

The decorator allows BindAI to treat the function as a tool that can be registered with an agent. Python type hints should be used whenever possible. They make the tool interface clearer and provide information that can be used when the tool is exposed to a language model.

Registering a Tool

A tool can be registered with an agent using .tool().

from bindai import Agent, tool


@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"The weather in {city} is sunny."


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .tool(get_weather)
    .build()
)

The builder keeps agent configuration in one place while allowing tools to be attached as capabilities.

Registering Multiple Tools

Use .tools() when an agent needs several capabilities.

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .tools(
        search,
        get_weather,
        calculate,
    )
    .build()
)

Multiple tools allow the model to select the capability that best matches the current request. For example:

User
  |
  +-- Search request ------> search()
  |
  +-- Weather request -----> get_weather()
  |
  +-- Calculation ---------> calculate()

How Tool Calling Works

At a high level, tool-enabled execution follows this process:

User
  |
  v
Agent
  |
  v
Language Model
  |
  v
Tool Selection
  |
  v
Tool Execution
  |
  v
Tool Result
  |
  v
Language Model
  |
  v
Final Response

The model determines whether a registered tool is appropriate for the request. When the model requests a tool, BindAI executes the corresponding callable and provides the result back to the ongoing agent execution. The model can then use the tool result when producing the final response or deciding what to do next.

Why Use Tools?

A language model does not automatically have access to application-specific capabilities or current external data. Tools can provide access to:

Live data
Internal APIs
Databases
Deterministic calculations
Application state
Business operations
External services
Knowledge retrieval

For example, instead of asking a model to perform a calculation itself, an application can expose a deterministic Python operation:

@tool
def multiply(a: int, b: int) -> int:
    return a * b

The agent can use the operation when appropriate.

Tool Parameters

Tool parameters are defined by the Python function signature.

@tool
def search(
    query: str,
    limit: int = 5,
): ...

This tool exposes two parameters:

query — the search query
limit — the maximum number of results

Type hints communicate the expected parameter types. Default values can be used when a parameter is optional. Prefer explicit, descriptive parameters over ambiguous arguments.

Type Hints

Type hints make tools easier to understand and integrate.

@tool
def multiply(
    a: int,
    b: int,
) -> int:
    return a * b

The signature communicates:

a            -> integer
b            -> integer
return value -> integer

Use clear type annotations for tool parameters whenever possible. They make tool contracts easier for both developers and language models to understand.

Tool Descriptions

Tool descriptions should clearly explain what an operation does. For example:

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"The weather in {city} is sunny."

A clear description helps the model determine when the tool is appropriate. Good descriptions should explain:

What the tool does
When it should be used
What its important parameters represent
What kind of result it returns

Avoid descriptions that are vague or overly broad.

Multiple Tool Calls

An agent execution can involve more than one tool call. For example:

User
  |
  v
Model
  |
  v
Search Tool
  |
  v
Model
  |
  v
Calculator Tool
  |
  v
Model
  |
  v
Final Response

This allows an agent to combine several capabilities during a single request. The execution system coordinates the interaction between the model, tools, and subsequent model responses. Applications should avoid assuming that every request results in exactly one tool call.

Tool Execution

When a model requests a registered tool, BindAI executes the associated callable. Conceptually:

Model
  |
  v
Tool Call
  |
  v
Python Function
  |
  v
Return Value
  |
  v
Model

The returned value becomes part of the ongoing execution and can be used by the model to continue the task. This allows an agent to combine language reasoning with deterministic application operations.

Tool Results

Tool execution produces a result that is handled by BindAI’s tool execution system. The result can represent successful output or an execution error. Application code should generally allow the agent execution layer to coordinate tool results rather than implementing provider-specific tool-call handling. For example, a tool can simply return its application result:

@tool
def get_customer_name(customer_id: str) -> str:
    return "Alex"

The agent execution system handles the interaction between the tool and the language model.

Tool Errors

Tools can fail during execution. For example:

@tool
def get_data():
    raise RuntimeError("Database unavailable.")

Applications should design tools to handle expected failures appropriately. For external systems, return or raise clear errors that provide enough information for the surrounding execution flow to understand what went wrong. Tool failures should not expose unnecessary internal details such as credentials, private connection information, or sensitive application state.

Reusing Tools

Tools can be reused across multiple agents.

weather = get_weather

support_agent.tool(weather)
sales_agent.tool(weather)
research_agent.tool(weather)

This keeps shared functionality in one implementation instead of duplicating the same logic across agents. Reusable tools are particularly useful for common capabilities such as:

Search
Data retrieval
Calculations
Internal APIs
External service operations

Tools and Agent Configuration

Tools are part of an agent’s capabilities and can be configured alongside its model, instructions, memory, knowledge, and other execution features. For example:

agent = (
    Agent.builder()
    .name("researcher")
    .model("openai:gpt-4.1-mini")
    .instructions("Research questions using the available tools.")
    .tools(search, get_weather, calculate)
    .build()
)

This keeps the agent’s capabilities explicit and close to the rest of its configuration. For larger projects, tools can be organized into dedicated modules:

my-ai-app/
├── agents/
│   └── assistant.py
│
├── tools/
│   ├── search.py
│   ├── weather.py
│   └── calculator.py
│
├── workflows/
│
└── tests/

The exact project structure is application-dependent.

Tool Context

Some tools may need access to information beyond their explicit function arguments. BindAI tools can participate in the execution context used by the agent. This can be useful for applications involving:

Runtime metadata
Execution state
Workflow state
Application state
User-specific information
External service configuration

The exact context available to a tool depends on the tool and execution mechanism being used. Keep tool interfaces explicit whenever possible. Use execution context when the capability genuinely depends on runtime information.

Tools and Memory

Tools can work alongside BindAI memory. For example, an agent might use:

User
  |
  v
Agent
  |
  +---- Memory
  |
  +---- Tool
  |
  v
Response

Memory provides conversation or application context, while tools provide executable capabilities. The two mechanisms solve different problems and can be combined in the same agent.

Tools and Knowledge

Tools can also complement BindAI’s knowledge and retrieval capabilities. For example:

Agent
  |
  +---- Knowledge / Retrieval
  |
  +---- Search Tool
  |
  +---- External API Tool
  |
  v
Final Response

Knowledge systems are useful for retrieving information from indexed content. Tools are useful when the agent needs to execute an operation or access a live external system.

Tools and Workflows

Tools can participate in workflow-driven applications. A workflow can coordinate agent execution while tools provide individual capabilities. Conceptually:

Workflow
   |
   v
Agent
   |
   +---- Tool A
   |
   +---- Tool B
   |
   +---- Tool C
   |
   v
Next Workflow Step

Use tools for individual operations and workflows for larger orchestration logic. Avoid putting complex multi-step orchestration directly inside a single tool.

External Services

Tools are a natural interface for external services. Examples include:

REST APIs
Databases
Search services
SaaS platforms
Internal business systems
Other application services

For repeated integrations, BindAI’s Connections package can provide a dedicated integration boundary. A tool can then expose a focused operation while the connection manages communication with the external service. For example:

Agent
  |
  v
Tool
  |
  v
Connection
  |
  v
External Service

This keeps external service details separate from the agent’s high-level behavior.

Designing Good Tools

Good tools should have a clear and limited responsibility. For example, prefer:

@tool
def get_weather(city: str): ...

over a single tool that attempts to handle:

weather
search
database access
email
file operations
payments

Small tools are easier for developers and language models to understand. Focused tools also make testing, error handling, reuse, and maintenance easier.

Tool Security

Tools can give an agent access to real application capabilities, so they should be treated as application boundaries. Consider:

Validate external inputs.
Limit access to sensitive operations.
Avoid exposing credentials to the model.
Avoid returning secrets in tool results.
Apply appropriate authorization in application code.
Keep destructive operations narrowly scoped.
Validate data before writing to external systems.

The language model should not be treated as a security boundary. Authorization and access control should remain enforced by the application and the systems behind the tool.

Tool Side Effects

Some tools only read information, while others modify application state. Examples of read operations:

search()
get_customer()
get_weather()

Examples of state-changing operations:

create_customer()
send_email()
update_record()
delete_document()

State-changing tools should be designed carefully. Where appropriate, applications should validate important parameters and require explicit confirmation for sensitive or irreversible actions.

Testing Tools

Tools should be tested independently from the language model whenever possible. A deterministic tool can be tested like normal Python application code:

def multiply(a: int, b: int) -> int:
    return a * b


assert multiply(2, 3) == 6

Tool integration tests can then verify that the tool is correctly registered with an agent. Useful test areas include:

Tool registration
Parameter handling
Successful execution
Error handling
External service failures
Security and authorization
Tool output formatting

Keeping tool logic independently testable makes agent behavior easier to debug.

Tool Calling and Providers

Tool calling is coordinated between BindAI and the selected model provider. The provider determines how tool calls are represented to the model, while BindAI manages the application-level tool execution. This architecture allows tools to remain largely independent of a specific provider. Conceptually:

                 BindAI Agent
                      |
                      v
               Model Provider
                      |
                      v
                 Tool Call
                      |
                      v
               BindAI Tool
                      |
                      v
               Python / API

This separation helps applications switch providers without rewriting their core tool implementations.

Tools and Multi-Agent Systems

Tools can be assigned to different specialist agents. For example:

                 Team
                  |
        +---------+---------+
        |         |         |
        v         v         v
    Research    Support   Operations
       |           |         |
    Search       CRM       APIs
    Tools        Tools     Tools

This allows each specialist agent to expose only the capabilities relevant to its role. Keeping tool sets focused can make multi-agent systems easier to reason about and maintain.

Best Practices

Give each tool one clear responsibility.
Use descriptive function and parameter names.
Add Python type hints.
Write concise and accurate tool descriptions.
Validate external inputs.
Keep tool outputs focused and useful.
Handle expected failures gracefully.
Avoid exposing secrets through tool inputs or outputs.
Apply authorization in application code.
Keep destructive operations narrowly scoped.
Avoid unnecessary side effects.
Reuse common tools across agents.
Prefer several focused tools over one large tool.
Test tools independently from the language model.
Use workflows for complex orchestration.
Use dedicated connections when an external integration benefits from a reusable connection boundary.

Summary

Tools extend BindAI agents with capabilities beyond language generation. The primary registration APIs are:

agent.tool(my_tool)

and:

agent.tools(
    search,
    calculate,
)

Tools can be created from Python functions or with the @tool decorator:

from bindai import tool


@tool
def multiply(a: int, b: int) -> int:
    return a * b

A complete builder-based agent can then expose the tool:

from bindai import Agent, tool


@tool
def multiply(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b


agent = (
    Agent.builder()
    .name("calculator")
    .model("openai:gpt-4.1-mini")
    .instructions("Use the calculator tool when arithmetic is required.")
    .tool(multiply)
    .build()
)

Once registered, tools can participate in agent execution and allow models to interact with application logic, external services, deterministic operations, memory, knowledge, and workflows. The result is an agent that can do more than generate text: it can use application capabilities and take actions as part of its execution.

​Tools Overview

​What Is a Tool?

​Creating a Tool

​Registering a Tool

​Registering Multiple Tools

​How Tool Calling Works

​Why Use Tools?

​Tool Parameters

​Type Hints

​Tool Descriptions

​Multiple Tool Calls

​Tool Execution

​Tool Results

​Tool Errors

​Reusing Tools

​Tools and Agent Configuration

​Tool Context

​Tools and Memory

​Tools and Knowledge

​Tools and Workflows

​External Services

​Designing Good Tools

​Tool Security

​Tool Side Effects

​Testing Tools

​Tool Calling and Providers

​Tools and Multi-Agent Systems

​Best Practices

​Summary